// Standard Prelude for the JSMR JavaScript MapReduce Environment.
// See: http://code.google.com/p/jsmr/

// JSMR
// The 'JSMR' Object is provided in the JavaScript execption environment before
// the prelude is loaded. It is used as a namespace for the JSMR prelude.
// ['JSMR' is defined in the JSMR environment]

// JSMR.log(level, msg, stack_depth = 0)
// ['JSMR.log()' is defined in the JSMR environment]
//
// Logs 'msg' at severity 'level' to the environment's logging facility.
//
// We provide the following LOG Levels:
//   JSMR.log.FATAL - Log a fatal error, which will abort execution.
//   JSMR.log.ERROR - Log an error.
//   JSMR.log.WARN  - Log a warning.
//   JSMR.log.INFO  - Log non-warning information.
//
// The 'stack_depth' parameter premits utility code to change the stack depth of
// the source line extracted by the 'JSMR.log()' method. For example, given the
// file 'script.js':
//   0: function foo() {
//   1:   JSMR.log(JSMR.log.INFO, "a b c");
//   2:   JSMR.log(JSMR.log.INFO, "x y z", 1);
//   3: }
//   4: function bar() {
//   5:  foo();
//   6: }
//   7: bar();
//
// We might expect to see the following log lines:
//   [INFO ex.js:2] a b c
//   [INFO ex.js:6] x y z

// Utility functions to simplify logging at a given level:
JSMR.log.fatal = function (msg, depth) {
  JSMR.log(JSMR.log.FATAL, msg, depth ? depth + 1 : 1);
}
JSMR.log.error = function (msg, depth) {
  JSMR.log(JSMR.log.ERROR, msg, depth ? depth + 1 : 1);
}
JSMR.log.warn  = function (msg, depth) {
  JSMR.log(JSMR.log.WARN,  msg, depth ? depth + 1 : 1);
}
JSMR.log.info  = function (msg, depth) {
  JSMR.log(JSMR.log.INFO,  msg, depth ? depth + 1 : 1);
}


// JSMR.require(path, [path, path, path, ...])
// ['JSMR.require()' is defined in the JSMR environment]
//
// 'JSMR.require()' loads each script in order provided, from their respective
// paths.  The meaning of a script's path string is determined by the JSMR
// environment, check the documentation for your execution environment.
//
// A given path will be included and executed by JSMR at most once.
//
// For example, given the following files:
//   foo.js:
//     JSMR.log.info("foo first")
//     JSMR.require("bar.js", "baz.js")
//     JSMR.log.info("foo second")
//
//   bar.js:
//     JSMR.log.info("bar first")
//     JSMR.require("foo.js", "baz.js")
//     JSMR.log.info("bar second")
//     
//   baz.js:
//     JSMR.log.info("baz first")
//     JSMR.require("foo.js")
//     JSMR.log.info("baz second")
//
// Were we to initially load 'foo.js', we might expect to see the following:
//   [INFO src/jsmr.cc:278] Loading Script: foo.js
//   [INFO foo.js:1] foo first
//   [INFO src/jsmr.cc:278] Loading Script: bar.js
//   [INFO bar.js:1] bar first
//   [INFO src/jsmr.cc:275] Not Reloading Script: foo.js
//   [INFO src/jsmr.cc:278] Loading Script: baz.js
//   [INFO baz.js:1] baz first
//   [INFO src/jsmr.cc:275] Not Reloading Script: foo.js
//   [INFO baz.js:3] baz second
//   [INFO bar.js:3] bar second
//   [INFO src/jsmr.cc:275] Not Reloading Script: baz.js
//   [INFO foo.js:3] foo second
